---
title: 人机协作
description: Add a human in the loop check for your agent executions
---

import { Aside, Code } from '@astrojs/starlight/components';
import humanInTheLoopExample from '../../../../../../examples/docs/human-in-the-loop/index.ts?raw';
import toolApprovalDefinition from '../../../../../../examples/docs/human-in-the-loop/toolApprovalDefinition.ts?raw';

本指南演示如何使用 SDK 内置的 Human in the loop 支持，在有人为干预时暂停并恢复智能体运行。

当前的主要用例是对敏感工具执行请求审批。

## 审批请求

你可以通过将 `needsApproval` 选项设为 `true`，或设为返回布尔值的异步函数，来定义一个需要审批的工具。

<Code
  lang="typescript"
  code={toolApprovalDefinition}
  title="工具审批定义"
  meta={`{10}`}
/>

### 流程

1. 如果智能体决定调用一个（或多个）工具，它会通过评估 `needsApproval` 来检查该工具是否需要审批。
2. 如果需要审批，智能体会检查审批是否已被批准或拒绝。
   - 如果尚未批准或拒绝，该工具将向智能体返回一条静态消息，说明该工具调用无法执行。
   - 如果缺少批准/拒绝，则会触发一个工具审批请求。
3. 智能体会收集所有工具审批请求并中断执行。
4. 如果发生任何中断，[执行结果](/openai-agents-js/zh/guides/results) 将包含一个 `interruptions` 数组，用于描述挂起的步骤。当某个工具调用需要确认时，会出现一个 `ToolApprovalItem`，其 `type: "tool_approval_item"`。
5. 你可以调用 `result.state.approve(interruption)` 或 `result.state.reject(interruption)` 来批准或拒绝该工具调用。
6. 处理完所有中断后，你可以通过将 `result.state` 传回 `runner.run(agent, state)` 来恢复执行，其中 `agent` 是触发整个运行的原始智能体。
7. 然后流程从第 1 步重新开始。

## 示例

下面是一个更完整的 Human in the loop 流程示例，它会在终端中提示审批，并将 state 临时存储到文件中。

<Code lang="typescript" code={humanInTheLoopExample} title="人工干预" />

参见[完整示例脚本](https://github.com/openai/openai-agents-js/tree/main/examples/agent-patterns/human-in-the-loop.ts)以获得可运行的端到端版本。

## 处理较长审批时间

Human in the loop 流程被设计为可在较长时间内中断，而无需持续运行你的服务器。如果你需要先结束请求并在之后继续，可以序列化 state 并稍后恢复。

你可以使用 `JSON.stringify(result.state)` 序列化 state，并在之后通过将序列化的 state 传入 `RunState.fromString(agent, serializedState)` 来恢复，其中 `agent` 是触发整个运行的智能体实例。

这样你就可以将序列化后的 state 存储到数据库，或与请求一同存储。

### 挂起任务的版本管理

<Aside>
  这主要适用于你在对智能体进行变更的同时，需要将序列化的 state
  长时间存储的情况。
</Aside>

如果你的审批请求需要较长时间且你打算以有意义的方式对智能体定义进行版本化，或升级你的 Agents SDK 版本，我们目前建议你通过使用包别名并行安装两个版本的 Agents SDK，自行实现分支逻辑。

实际做法是为你的代码分配一个版本号，并将其与序列化的 state 一起存储，同时在反序列化时引导到你代码的正确版本。
